程式說明文件 a401 Generate Web Page

根據【漢字注音】工作表轉製漢字標音【網頁】。

程式架構

  1. 配置類別 WebPageConfig

  2. 網頁生成器類別 WebPageGenerator

  3. 結構化函數組織

  4. 改善的錯誤處理與日誌

  5. 程式風格一致性

循序圖

  1. 程式執行流程循序圖 - 展示完整執行流程

  2. Ruby 標籤生成循序圖 - 詳細的標音邏輯

  3. 類別互動關係圖 - 展示物件協作

  4. 資料流向圖 - 從輸入到輸出

sequenceDiagram participant User as 使用者 participant Main as main() participant Process as process() participant GenWebPage as generate_web_page() participant Config as WebPageConfig participant PiauIm as PiauIm participant Generator as WebPageGenerator participant Sheet as Excel Sheet participant HTML as HTML 輸出 User->>Main: 執行程式 activate Main Main->>Main: 初始化日誌 Main->>Main: 取得程式資訊 Main->>Main: 記錄程式開始 Main->>Main: 取得作用中 Excel 活頁簿 alt 無法取得活頁簿 Main->>Main: 返回 EXIT_CODE_NO_FILE Main->>User: 結束 end Main->>Process: 呼叫 process(wb) activate Process Process->>Process: 記錄作業開始 Process->>GenWebPage: 呼叫 generate_web_page(wb) activate GenWebPage GenWebPage->>Config: 建立 WebPageConfig(wb) activate Config Config->>Sheet: 讀取 Excel Named Range Config->>Sheet: 讀取標音相關參數 Config->>Sheet: 讀取網頁格式設定 Config-->>GenWebPage: 返回配置物件 deactivate Config GenWebPage->>PiauIm: 建立 PiauIm(han_ji_khoo_name) activate PiauIm PiauIm-->>GenWebPage: 返回標音物件 deactivate PiauIm GenWebPage->>Generator: 建立 WebPageGenerator(config, piau_im) activate Generator Generator-->>GenWebPage: 返回生成器物件 deactivate Generator GenWebPage->>Sheet: 啟用工作表 GenWebPage->>Generator: 呼叫 generate_web_page(sheet, wb) activate Generator Generator->>Generator: 生成圖片 HTML Tag Generator->>Generator: 呼叫 generate_title_with_ruby() loop 讀取標題字元 Generator->>Sheet: 讀取標題儲存格 Generator->>Generator: 判斷是否為漢字 alt 是漢字 Generator->>Generator: 呼叫 generate_ruby_tag() Generator->>Generator: 生成 Ruby 標籤 else 非漢字 Generator->>Generator: 直接輸出 end end Generator->>Generator: 生成文章 Div 標籤 loop 逐列處理工作表內容 Generator->>Sheet: 讀取儲存格內容 alt 結尾標示 'φ' Generator->>Generator: 設置 End_Of_File = True Generator->>Generator: 中斷迴圈 else 換行標示 '\n' Generator->>Generator: 輸出換行標籤 Generator->>Generator: 重置字數計數 else 非漢字 alt 標點符號 Generator->>Generator: 輸出標點符號 else 空白 Generator->>Generator: 輸出全形空白 else 其他字元 Generator->>Generator: 輸出其他字元 end Generator->>Generator: 字數計數 +1 else 漢字 Generator->>Sheet: 讀取漢字標音儲存格 Generator->>Generator: 轉換為 TLPA 音標 Generator->>Generator: 呼叫 generate_ruby_tag() Generator->>Generator: 生成 Ruby 標籤 Generator->>Generator: 字數計數 +1 end alt 達到每列字數限制 Generator->>Generator: 輸出換行標籤 Generator->>Generator: 重置字數計數 end end Generator->>Generator: 輸出結束標籤 Generator-->>GenWebPage: 返回 HTML 內容 deactivate Generator GenWebPage->>GenWebPage: 生成輸出檔案名稱 GenWebPage->>GenWebPage: 構建 meta 標籤 GenWebPage->>HTML: 呼叫 _create_html_file() activate HTML HTML->>HTML: 組合 HTML 模板 HTML->>HTML: 建立輸出目錄 HTML->>HTML: 寫入 HTML 檔案 HTML-->>GenWebPage: 返回 deactivate HTML GenWebPage->>GenWebPage: 記錄完成訊息 GenWebPage-->>Process: 返回 EXIT_CODE_SUCCESS deactivate GenWebPage Process->>Sheet: 啟用【漢字注音】工作表 Process->>Process: 記錄作業結束 Process-->>Main: 返回 EXIT_CODE_SUCCESS deactivate Process Main->>Sheet: 啟用【漢字注音】工作表 Main->>Main: 儲存檔案 (save_as_new_file) alt 儲存成功 Main->>Main: 記錄儲存路徑 else 儲存失敗 Main->>Main: 記錄錯誤訊息 end Main->>Main: 記錄程式結束 Main->>User: 返回結束代碼 deactivate Main

WebPageGenerator 內部流程 - Ruby 標籤生成

sequenceDiagram participant Generator as WebPageGenerator participant PiauIm as PiauIm participant RubyTag as Ruby標籤 Generator->>Generator: generate_ruby_tag(han_ji, tai_gi_im_piau) Generator->>Generator: 分解台語音標 Generator->>Generator: split_tai_gi_im_piau() Generator->>Generator: 取得聲母、韻母、聲調 alt 聲母為空 Generator->>Generator: 設置聲母為 "ø" else 聲母存在 Generator->>Generator: 使用讀取的聲母 end alt 網頁格式為「無預設」 alt 標音方式為「上及右」 Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回上方標音 Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回右方標音 else 標音方式為「上」 Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回上方標音 else 標音方式為「右」 Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回右方標音 end else 網頁格式為特定類型 alt 格式為 POJ/TL/BP/TLPA_Plus/SNI Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回上方標音 else 格式為 TPS Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回右方標音 else 格式為 DBL Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回上方標音 Generator->>PiauIm: 呼叫 han_ji_piau_im_tng_huan() PiauIm-->>Generator: 返回右方標音 end end Generator->>Generator: _build_ruby_tag(han_ji, siong_piau_im, zian_piau_im) alt 僅上方標音 Generator->>RubyTag: 生成上方標籤 <rt> else 僅右方標音 Generator->>RubyTag: 生成右方標籤 <rtc> else 上方及右方標音 Generator->>RubyTag: 生成上方 <rt> + 右方 <rtc> else 無標音 Generator->>RubyTag: 生成純文字 <span> end RubyTag-->>Generator: 返回 Ruby HTML 標籤

類別互動關係圖

classDiagram class WebPageConfig { - wb: Workbook - TOTAL_LINES: int - CHARS_PER_ROW: int - ROWS_PER_LINE: int - start_row: int - start_col: int - end_row: int - end_col: int - han_ji_khoo_name: str - ue_im_lui_piat: str - piau_im_huat: str - piau_im_format: str - piau_im_hong_sik: str - siong_pinn_piau_im: str - zian_pinn_piau_im: str - title: str - image_url: str - output_dir: str - zu_im_huat_list: dict __init__(wb) } class PiauIm { - han_ji_khoo_name: str han_ji_piau_im_tng_huan() hong_im_tng_tai_gi_im_piau() } class WebPageGenerator { - config: WebPageConfig - piau_im: PiauIm __init__(config, piau_im) + generate_ruby_tag(han_ji, tai_gi_im_piau) + generate_title_with_ruby(sheet, wb) + generate_web_page(sheet, wb) - _build_ruby_tag(han_ji, siong_piau_im, zian_piau_im) } class main { + main() } class process { + process(wb) } class generate_web_page { + generate_web_page(wb, sheet_name) - _create_html_file(output_path, content, title, head_extra) } main --> process: 呼叫 process --> generate_web_page: 呼叫 generate_web_page --> WebPageConfig: 建立 generate_web_page --> PiauIm: 建立 generate_web_page --> WebPageGenerator: 建立 WebPageGenerator --> WebPageConfig: 使用 WebPageGenerator --> PiauIm: 使用 WebPageGenerator --> main: 生成HTML

資料流向圖

graph TD A["Excel 活頁簿"] -->|讀取 Named Range| B["WebPageConfig"] A -->|讀取工作表| C["WebPageGenerator"] B -->|提供配置| C D["PiauIm"] -->|標音轉換| C C -->|處理標題| E["Ruby 標籤"] C -->|處理內容| E C -->|處理圖片| E E -->|組合| F["HTML 內容"] F -->|輸出| G["HTML 檔案"] C -->|記錄| H["Console 日誌"] B -->|記錄| H